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Free  MQ!  MQ  Clients  and  what  you  can 
do  with  them 


Mark  Taylor 

marke_taylor@uk.  ibm.  com 

WMQ  Technical  Strategy,  IBM  Hursley 
Session  11510 
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SHARK 

■ What  are  the  MQ  clients  ? 

■ The  MQ  client  and  how  it  works 

■ How  to  connect  a client  to  a server 

• Channel  Table  Configuration 

■ What  facilities  are  available  to  clients 

■ Transactions 

• Global  Transactions 

• Security 

• Exits 

{ SHARE 
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What  is  a client  ? 

■ Allows  access  to  messaging  API  on  a 

different  machine  than  the  queue  manager\  \ / 

• Simpler  administration 

• Same  programming  capabilities  (almost) 

• Cheaper 

• Free  in  most  cases 

■ However 


No  network  - No  messaqin 
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Messaging  Clients 
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Which  client  to  use 


rl 


■ Power  of  MQI  vs  Portability  of  JMS 

JMS  does  not  tie  you  to  a provider  (99%  portable) 
JMS  available  for  non-JAVA  languages  in  XMS 
• XMS  is  IBM  specific  though 


■ How  important  is  speed  ? 

C tends  to  be  faster  than  Java 
MQI  tends  to  be  faster  than  JMS/XMS 

■ Mobile/small  environments 

• Consider  MQTT 

••••• 

: SHARE 
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What  is  an  MQ  Client  ? 
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Server 

Model 


Application 


MQ  Server 
Library 


local  or  bindings  mode 


MQ 

Server 


Client 

Model 


j Application 


MQ  Client 
Library 


MQ 

Server 
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How  does  a client  work  ? 


• Requires  network  access 

• Each  MQI  Call  shipped  to  server 

• Response  returned  to  application 


MQI  Calls 

MQCONN 

MQCONNX 

MQDISC 

MQOPEN 

MQCLOSE 

MQSUB 

MQPUT 

MQPUT1 

MQGET 

MQCB 

MQCTL 

MQINQ 

MQSET 

MQCMIT 

MQBACK 

Complete  your  sessions  evaluation  online  at  SHARE.org/AnaheimEval 
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How  to  install  a client 


1 . Install  a MQ  client  and  MQ  server  system 

Install  MQ  server  using  the  SERVER  CD  ROM 
Install  the  MQ  client  using  the  CLIENT  CD  ROM 


2. 


3. 


Install  MQ  client  and  server  on  the  same  machine 
Install  MQ  server  from  SERVER  CD  ROM 
and  select  MQ  clients  you  wish  to  install 


Install  MQ  client  from  SupportPacs  site 
Download  SupportPac 
Extract  and  run  installation  program 


See  the  platform  Quick  Beginnings  for  specific  details 
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What  about  Licensing  ? 


SHARE 


Installable  clients  can  be  downloaded  for 
free 

• Available  on  many  platforms 

Client  attachment  feature  required 
for  z/OS 

Extended  Transactional  (XA)  Clients  are 
now  free 
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Building  a client  application  lujlv 

■ Compile  your  application  as  you  would  for  local  application 

■ Make  sure  you  link  your  application  with  CLIENT  libraries 

• libmqic* *  for  "C"  applications  on  UNIX  systems 

• mqic32.lib  for  "C"  applications  on  Windows 

• imqb23*  imqc23*  for  "C++"  applications 

■ Take  care  when  linking  threaded  programs 

• e.g.  Iibmqic_r.a  for  AIX 

■ Ensure  that  the  correct  runtime  libraries  are  available 

• e.g. mqic32.dll  for  Windows 

■ From  V7.1  onwards,  libmqm  can  also  act  as  client 

Support  for  multi-version  installations 

: SHARE 
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How  to  connect  a client  to  a server 
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■ The  client  must  be  able  to  identify  which  channel  it  should  use  to 
communicate  with  the  queue  manager 

■ How  to  specify  the  client's  connection  to  a queue  manager: 

Explicitly  on  the  MQCONNX  verb 
• MQSERVER  variable 
Client  channel  tables 


Java  client  programs  use  either  the  MQEnvironment  Java  class  or 
JNDI  (using  JMS)  or  explicit  properties 


Client  machine 

Complete  your  sessions  evaluation  online  at  SHARE.org/AnaheimEval 
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The  easiest  way  to  define  a client  channel. 

BUT  has  default  CLNTCONN  properties,  ie. 

• No  security,  such  as  SSL 

• No  exits 

• etc 

Takes  precedence  over  channel  tables 

but  is  superseded  by  the  use  of  the  MQCNO  structure. 


set  MQSERVER=ChannelName/TransportType/ConnectionName 

In  Windows:  use  Control  Panel  ->  System  ->  Advanced  ->Environment  Variables 
• In  UNIX:  export  MQSERVER 


■ Examples: 

• MQSERVER=SYSTEM.DEF.SVRC0NN/TCP/1 27.0.0.1 
MQSERVER=SYSTEM.DEF.SVRCONN/TCP/1 27.0.0.1  (1415) 
MQSERVER=SYSTEM.DEF.SVRCONN/TCP/JU  PITER. SOLAR. SYSTEM.  UNI 
MQSERVER=SYSTEM.DEF.SVRCONN/LU62/BOX99 

Complete  your  sessions  evaluation  online  at  SHARE.org/AnaheimEval 
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Channel  definition  tables 


■ A channel  definition  table  is: 

A binary  file  (not  editable  by  a user) 

Created  by  RUNMQSC  (or  other  MQ  mechanism)  as 
AMQCLCHL.TAB  (by  default)  when  client  channels  are  defined 

• Use  CSQUTIL  MAKECLNT  function  on  z/OS 

Located  in  directory  (by  default): 

• <mq  root>\qmgrs\QMGRNAME\@ipcc  (Windows) 

• <mq  root>/qmgrs/QMGRNAME/@ipcc  (UNIX) 

Read  by  the  client  if  no  MQSERVER  variable  defined  and 
MQCONNX  options  are  not  used 


CompleteyoursessionsevaluationonlineatSHARE.org/AnaheimEval  . in  Anaheim 


r\ 

How  do  I create  and  deploy  a channel  table  ? 


RUNMQSC 

def  chl(...)  chltype(clntconn) .... 


<mq  root>\qmgrs\QMGRNAME\@ipcc  (NT) 
<mq  root>/qmgrs/QMGRNAME/@ipcc  (Unix) 

copy 

c:\mqm\qmgrs\qmgrname\@ipcc\AMQCLCHL.TAB 

to 

z:\mytable.tbl 


MYTABLE.TAB 
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Using  Channel  Definition  Tables:  Example  2 


■ Multiple  routes  to  the  same  Queue  Manager 

def  chl(chll)  ....trptype(tcp)  conname(hostl)  qmname(mars) 
def  chl(chl2) . . . .trptype(tcp)  conname(tokenring)  qmname(venus) 
def  chl(chl3) . . . .trptype(tcp)  conname(ethernet)  qmname(venus) 
def  chl(chl4) . . . .trptype(tcp)  conname(dialup)  qmname(venus) 
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Using  Channel  Definition  Tables:  Example  3 


■ How  do  we  have  back-up  Queue  Managers  ? 

def  chl(chll)  ....trptype(tcp)  conname(ip.mars)  qmname(planet) 
defchl(chl2)  ....trptype(tcp)  conname(ip.venus)  qmname(planet) 


def  chl(chl5)  ....trptype(tcp)  conname(ip.pluto)  qmname(planet) 


MQCONN  (“planet", hConn,cc,rc  ); 


THIS  DOESN’T  WORK  (quite!) 
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Using  Channel  Definition  Tables:  Example  4 


■ How  do  we  have  back-up  Queue  Managers  ? 

def  chl(chll)  ....trptype(tcp)  conname(ip.mars)  qmname(planet) 
defchl(chl2)  ....trptype(tcp)  conname(ip. venus)  qmname(planet) 


def  chl(chl5)  ....trptype(tcp)  conname(ip.pluto)  qmname(planet) 


MQCONN  (“*planet",hConn,cc,rc  ); 


AMQCLCHL.TAB 


o 


MQ  Client 


This  works  ! 


Notice  the  preceding  the  Queue  Manager  name 
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Using  Channel  Definition  Tables:  Example  5 


SHARE 


How  do  we  have  back-up  Queue  Managers  ? 

def  chl(chll)  ....trptype(tcp)  conname(ip.mars)  qmname() 
defchl(chl2)  ....trptype(tcp)  conname(ip.venus)  qmname() 


def  chl(chl5)  ....trptype(tcp)  conname(ip.pluto)  qmnameQ 


MQCONN  (“  ”,hConn,cc,rc  ); 


AMQCLCHL.TAE 


£ 


o 


MQ  Client 


This  works  too  ! 
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Workload  Balancing  client  connections 


MQCONNC 


Name 

CHLTYPE 

TRPTYPE 

CONNAME 

QMNAME 

CLNTWGHT 

AFFINITY 

chll 

CLNTCONN 

TCP 

ip.mars 

planet 

4 

PREFERRED 

chl2 

CLNTCONN 

TCP 

ip.venus 

planet 

4 

PREFERRED 

chl3 

CLNTCONN 

TCP 

ip.pluto 

planet 

2 

PREFERRED 

venus 


pluto 
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Using  MQCONNX 


MQCONNX  ( qmgr  name,  CNO,  Hconn,  cc,  rc) 


MQCNO  - Connection  Options : 

MQCHAR4  Strucld; 

MQLONG  Version; 

MQLONG  Options; 

MQLONG  ClientConnOf f set; 

MQPTR  ClientConnPtr ; 


/*  Structure  identifier 
/*  Structure  version  number 

/*  Options  that  control  the  action  of  MQCONNX 


*/ 

*/ 

*/ 


/*  Offset  of  MQCD  structure  for  client  connection  */ 
/*  Address  of  MQCD  structure  for  client  connection*/ 


MQCD  - 

Channel  Definition 

MQCHAR 

ChannelName [20] ; 

/* 

Channel  definition  name 

*/ 

MQCHAR 

ConnectionName [264] ; 

/* 

Connection  name 

*/ 

□ 


If  used,  overrides  MQSERVER  and  CHANNEL  tables 
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Using  MQCONNX 
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MQCD  cd  = {MQCD_CLIENT_CONN_DEFAULT}; 
cno. Version  = MQCNO_VERSION_2;  //  CD  ignored  if  CNO  not  V2  or  greater 
cno.ClientConnPtr  = &cd; 

strcpy(cd.ChannelName, "SYSTEM. DEF.SVRCONN“); 
strcpy(cd.ConnectionName, "VENUS. SOLAR. SYSTEM.  UNI“); 

MQCONNX  ( &cno,  &hQm,  &cc,  &rc) 
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► 

MQ  Cloud  Support:  Pre-Connect  Exit 

■ Supports  movement  by  some  to  “Utility  Compute”,  Private 
Cloud  configs,  etc. 

• Rapid  provision  of  applications  allied  with  need  to  further 
decouple  Client/Server  connectivity 

Server  applications  might  move  location  - new  addresses  or 
queue  managers 

■ MQ  Client  connects  to  a “service”  rather  than  specific 
Queue  Manager 

■ Can  transparently  change  location  of  MQ  server-side 
applications 

• No  client  code  changes  needed 

• No  configuration  files  need  to  be  updated  at  client  machine 

• JMS/XMS  applications  already  do  this  via  JNDI  lookupSHARE 
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Dynamic  Connections:  CCDT 
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■ How  it  used  to  be  done  . . . 

■ The  CCDT  is  used  to  select  a queue  manager  from  a list 

• Based  on  a pseudo-queue  manager  name  prefixed  with  “* * * * * *••••” 
CCDT  is  a locally-accessible  file 


Dynamic  Connections:  Pre-Connect  Exit 


Look  up  in  a directory  such  as  LDAP 
Make  choice  based  on  any  accessible  criteria 
Is  system  running? 

• Workload? 

Where  is  the  application  running  now?  ^ use  pluto 

No  needed 


MQCONN  (“planet", hConn,cc,rc  ); 


MQ  Client 





pluto 
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Check  the  error  logs! 

Server  error  log  <root>\qmgrs\<QM>\errors\AMQERR01.LOG 
Client  error  log  <root>\errors\AMQERR01  .LOG 

Double  check  the  MQSERVER  variable 

Does  the  amqsputc  sample  work? 

Is  the  network  working  ? 

Can  you  "tcp  ping"  the  host? 

Is  there  an  MQ  listener  running? 


Is  the  channel  table  specified  correctly 

Do  the  environment  variables  point  to  the  right  place? 
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WMQ  V7  Enhancements  for  Client  Performance 
Read  Ahead 

"Read  Ahead"  for  Receiving  Messages/Publications: 

Messages  sent  to  a client  in  advance  of  MQGET,  queued  internally 
Administrative  choice  - no  application  changes  needed 
Higher  performance  in  client 


(S 

| 

) 

MQCONN 

Client 

MQOPEN 

MQGET 

MQGET 

r\ 

MQGET 

9 J 

Complete  yourses: 

1 

Request  for 
‘n’  messages 
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WMQ  V7  Enhancements  for  Client  Performance  T 
Asynchronous  Put 

"Asynchronous  Put"  for  Sending/Publishing  Messages: 

Application  can  indicate  it  doesn't  want  to  wait  for  the  real  return  code 
• Maybe  look  for  return  code  later  - MQSTAT  verb 
Maintains  transactional  semantics 
Higher  performance  in  client 


0 3 

MQCONN 

MQOPEN 

MQOPEN 

MQPUT 

iv/inDI  IT 

Client 

1 : 

Server 

IVIvJi  U 1 
MQPUT 

MQPUT 

MQCMIT 
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WMQ  V7  Enhancements 

Sharing  Conversations 

■ Controlled  by  SHARECNV  channel  attribute 

• 0 All  sharing  is  off ; channel  operates  in  MQ  V6  mode 

• 1 Sharing  is  off  but  channel  still  operates  in  MQ  V7  mode 

Many  Sharing  up  to  negotiated  value  : Default  10 


Q1 


Q2 


Q3 

•;  SHARE 
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Programming  Considerations 


rl 


■ Take  care  when  specifying  the  queue  manager  name  on  MQCONN  if  using  client 
channel  definition  table... 

■ Most  MQI  calls  are  SYNCHRONOUS  and  tend  to  be  slower  than  in  a server 
environment. 

■ Always  be  prepared  for  MQRC_CONNECTION_BROKEN. 

■ Always  code  MQGMO_FAIL_IF_QUIESCING. 

■ For  optimum  performance  don’t  use  really  short  lived  connections  (MQCONNs) 

■ Carefully  code  MQWMJNLIMITED  on  MQGET  calls. 

■ Use  Asynchronous  MQPUT  and  Read  Ahead  if  appropriate 

As  always  If  you  don't  want  to  lose  messages,  code  MQ*_SYNCPOINT  on 
MQGET  and  MQPUT  calls  then  issue  MQCMIT 

* SHARE 
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Automatic  Client  Reconnection 
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■ Client  library  provides  reconnection  logic  on  detection  of  a failure 

■ Tries  to  hide  queue  manager  failures  by  restoring  state  automatically 


Can  reconnect  to  the  same  or  different  QMgr 
Re-opens  queues,  re-establishes  subscriptions  ... 
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Automatic  Client  Reconnection: 
What  causes  reconnection? 


£» 


■ Only  explicit  ends  or  failures 

• Communications  failure 

Queue  Manager  or  Listener  failure 

• STOP  CONN 

• endmqm  -s  or  endmqm  -r 

■ The  following  will  not  cause  reconnect 

• STOP  CHANNEL 

• Any  other  endmqm 
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Automatic  Reconnection:  MQI  Considerations 


■ Some  MQI  options  will  fail  if  you  have  reconnection  enabled 

Using  MQPMO/MQGMO_LOGICAL_ORDER,  MQGET  gives 
MQRC_RECONNECT_INCOMPATIBLE 

■ New  MQCONNX  options 

MQCNORECONNECT 

MQCNO_RECONNECT_Q_MGR 

MQCNO_RECONNECT_DISABLED 

■ MQPUT  of  PERSISTENT  message  outside  of  syncpoint 

• May  return  MQRC_CALL_INTERRUPTED 

■ Event  handler  notified  of  reconnection  ‘events’ 

■ MQSTAT  may  return  only  a ‘subset’  of  information 

Reconnection  may  have  occurred  during  a message  sequence 
Can  be  used  to  query  reconnection  status 

: SHARE 
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Transactions 


MQ  Client  MQ  Server 


Message  Is  Lost! 
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Global  Transactions 
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MQ 

Server 


MQPUT/GET 
EXEC  SQL 
SQL  COMMIT 
MQCMIT 


Database 

Server 

Multiple  Resource  Managers  involved  in  the  transaction 
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Extended  Transactional  Client 


ft 


Local 

Application 


, Queue 
^ Manager 


XA 

TM 


App 


NODE  1 


Database 

client 


Database  Server 


NODE  2 


Extended 

Transactional 

Client 
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Client  Security 
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Client  Security  - SSL 


SHARE 


DEF  CHANNEL('SYSTEM.DEF.CLNTCONN') 
CHLTYPE(CLNTCONN) 

SSLCIPH('RC4_MD5_US')  a 

SSLPEER('CN=“user",  0="IBM",C="UK",)  V\ 


SSL  facility 
key  repository 
MQSSLKEYR 
environment  variable 

Client 


7 

/ Authentication, 

\ Encryption,  Integrity 


DEF  CHANNEL  ('SYSTEM. DEF.SVRCONN') 
CHLTYPE(SVRCONN) 
SSLCAUTH(REQUIRED) 
SSLCIPH('RC4_MD5_US') 
SSLPEER('CN="*",  0="IBM",  C="UK'") 


SSL  facility 
key  repository 


Server 
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Exits 


Client 


MQCONN(..) 

MQOPEN(..) 

MQPUT(..) 


Security 


Send 


Receive 


<c 


=> 

o 


Security 


Receive 


r 

1 

r< 

4 1 

Send 

Message  exits  and  Retry  Exits  are  not  applicable 
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Summary 


ft 


■ Clients  are  a simple,  low  administration  and  cheap  way  of 
providing  queuing  throughout  your  network. 

■ Consider  which  client  to  use  based  on 

• Programming  Language  required  (C,Java,C#,  C++) 

• Programming  model  required  (MQI  vs  JMS) 

• Performance 

■ Client  applications  can  do  the  same  as  local  applications 

• However,  no  network  - no  queuing 
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